S210: User Management Module Modernization Plan

Session: 210 Branch: session-210 Sub-session completed: 210.1 (spec + design) Date: 2026-03-12 Status: Spec complete, implementation pending

1. Session Mission

Modernize the modules/core-modules/user-management module to become a production-ready, portable core module that:

1. Uses real backend-api endpoints instead of mock data
2. Replaces NGXS state management with autoFlashState from @storage-system
3. Incorporates the corrected L0-L4 user tier hierarchy established in Session 209
4. Supports both immutable SystemRoles and custom space-level roles
5. Works in both gspace1 AND dynamically generated platforms (portability requirement)

The broader context: this module is a core-module — it will be reused across every platform generated by the GoGrab platform builder. It must be architecturally clean, portable, and correctly enforce the user hierarchy.

2. Work Completed

2.1 Vitto Governance Hardening (Session 209, carried into 210)

Eight files modified to fix a foundational misalignment where developers were incorrectly placed at L0 instead of executives:

2.2 Design Spec Written and Reviewed

Complete spec at: docs/superpowers/specs/2026-03-12-user-management-module-modernization-design.md

Key design decisions:

• Approach B chosen: Rebuild from gmodules1 as the base (it has 13 components, signals, standalone, domain events, workflow state machine — all modern patterns)
• Dual-layer data access: Repository (domain queries, caching, events) + API Service (HTTP, configurable base URL) — required for portability to generated platforms
• autoFlashState for UI state only: Filters, pagination, view mode, selection persisted via @storage-system. User/role data comes from backend via HTTP.
• Both SystemRoles + custom roles: SystemRoles are immutable platform-wide; custom roles can be created per-space
• Backend path: New AdminUsersController at /api/admin/users (avoids route conflict with existing /api/users/me/*)
• Two orthogonal classification systems documented: role (UserRole — access control) vs userType (RegistrationUserType — hierarchy category)

2.3 MCP Intelligence Captured

• 4 architectural decisions logged with calibrated confidence (0.93-0.97)
• 2 conventions added (security governance + tier hierarchy)
• 4 outcomes reported as successful
• Decision IDs: dev_1773339083867_uy3tzq1, dev_1773339093192_dic0kif, dev_1773339102249_nxwkony, dev_1773339111511_l40lg1a

2.4 Documentation Created

• docs/english/Progress/S209-vitto-governance-and-tier-hierarchy.md — Non-developer-friendly progress report
• docs/superpowers/specs/2026-03-12-user-management-module-modernization-design.md — Full design spec
• Memory file: s209-tier-hierarchy-governance.md in Claude memory

3. Current System State

What Works

• Tier hierarchy is correct across the codebase: auth.types.ts, auth-core.constants.ts, roles.guard.ts all aligned on L0=executive(90) through L4=platform_user(10)
• Vitto governance endpoints are guarded: Executive instruction create/update/delete requires @Roles(SystemRoles.EXECUTIVE); persona mutations require @Roles(SystemRoles.ADMIN)+
• Hierarchy-aware RolesGuard: Both backend-api and backend-vitto-api use the same shared guard from @libs-api/auth-core with proper level-based inheritance
• Frontend recognizes executive role: BrainContextService.isExecutive, VittoSettingsComponent.isExecutive, sidebar shows Developer section for executives

What Exists But Is Not Functional

• gspace1 user-management module (modules/core-modules/user-management/): Has 8 components, mock API, NGXS state — fully functional with fake data but NOT wired to real backend
• gmodules1 user-management module (gmodules1/libs/modules/user-management/): Has 13 components, more modern patterns — also uses mock API, more complete than gspace1 version
• Backend admin endpoint (GET /api/admin/users): Exists in AdminStatsController but only supports basic list with limit, skip, search — no full CRUD, no role management, no status workflow

What Is Missing

• Real backend CRUD endpoints for user management (create, update, delete, status change, role assignment, bulk operations)
• Role schema and endpoints in backend-api (custom roles with permissions)
• autoFlashState integration in the user-management module (currently uses NGXS)
• Corrected tier hierarchy in user-management module models (module still uses old role definitions)
• Connection between module and real backend-api (module uses mock API interceptor)

4. Critical Gaps

Gap 1: No Backend CRUD for L1/L2 Users

Why it matters: The user-management module cannot function without backend endpoints to create, update, delete, and manage users. The existing backend only has: (a) self-registration at /api/auth/register, (b) basic admin list at /api/admin/users, (c) platform user (L4) CRUD at /api/spaces/:spaceId/universes/:universeId/users.

Root cause: The backend was built incrementally — auth first, then platform users for generated platforms. Full admin user CRUD was never needed because there were only 2 founders + developers accessing the system directly.

What prevents correct behavior: Without these endpoints, the frontend module has no backend to talk to. The mock API masks this completely.

Gap 2: No Role Schema or Endpoints in Backend

Why it matters: Custom space-level roles (e.g., "Content Reviewer", "Billing Manager") require a Role schema in MongoDB and CRUD endpoints. SystemRoles are constants in code, but custom roles must be persisted.

Root cause: Roles were hardcoded as string arrays on the User document (roles: ['user']). No dedicated Role entity was ever created in backend-api.

Gap 3: Module Uses NGXS (Incompatible with Generated Platforms)

Why it matters: Generated platforms do NOT include NGXS (removed in S206). If the user-management module uses NGXS, it cannot be embedded in generated platforms.

Root cause: The module was built before the decision to remove NGXS from generated platforms.

Gap 4: Module Models Don't Reflect Corrected Tier Hierarchy

Why it matters: The module's user.model.ts defines SystemRoles as ADMIN > MANAGER > USER > VIEWER — missing EXECUTIVE entirely. Role hierarchy enforcement in UserRoleManagerComponent is based on the old 4-level hierarchy.

Root cause: Session 209 corrected the hierarchy in auth-core and Vitto, but the user-management module was not updated.

Gap 5: Dynamic CRUD Generation Strategy Undefined

Why it matters: The user-management module needs to work across dynamically generated platforms, each with their own backend. The strategy for how modules discover and connect to their backend hasn't been formalized beyond "configurable base URL".

Root cause: This is an architectural decision that hasn't been made yet. The user explicitly asked to discuss this as a follow-up.

5. Prioritized Recommendations

Tier 1 — High leverage / low effort

1.1 Write implementation plan using writing-plans skill

• What: Convert the spec into a step-by-step implementation plan with file-level granularity
• Why: The spec defines WHAT to build; the plan defines the BUILD ORDER and dependencies
• Effort: 30 minutes
• Dependencies: Spec is complete (done)

1.2 Implement models & types with L0-L4 hierarchy

• What: Update user.model.ts, user-api.model.ts, role.model.ts, role-api.model.ts, user-filters.model.ts with corrected tier hierarchy, SystemRoles alignment, proper request/response types
• Why: Everything else depends on the type definitions being correct
• Effort: 1-2 hours
• Dependencies: None (foundation layer)

1.3 Implement autoFlashState for UI state

• What: Replace NGXS UserState with autoFlashState signals for filters, pagination, viewMode, bulkSelection. Transient state (loading, error, selectedUser, total) as plain signals.
• Why: Removes NGXS dependency, enables portability to generated platforms
• Effort: 1-2 hours
• Dependencies: Models (1.2)
• Key import: import { autoFlashState } from '@storage-system'
• Pattern reference: libs/libs-foundational/storage-system/src/flash/helpers/auto-flash-state.ts
• Usage reference: docs/english/GoGrab-Space/theme-system/flash-persistence-integration.md

Tier 2 — Medium effort / high impact

2.1 Implement API Service + Repository layers

• What: UserApiService (extends BaseCrudApiService<User> if available, otherwise standalone HTTP service), RoleApiService, UserRepository, RoleRepository. Configurable base URL via injection token.
• Why: Data access layer that all components depend on
• Effort: 3-4 hours
• Dependencies: Models (1.2)
• Key: Base URL must be injectable (for gspace1: API_BASE_URL, for generated platforms: whatever provideApiConfig() provides)

2.2 Implement backend-api endpoint enhancements

• What: New AdminUsersController at /api/admin/users with full CRUD + status + roles + bulk. New Role schema. New AdminRolesController.
• Why: Frontend module needs a real backend
• Effort: 4-6 hours
• Dependencies: None (can be done in parallel with frontend)
• Location: APIs/backend-api/src/app/admin/
• Must use: @UseGuards(JwtAuthGuard, RolesGuard) at class level, @Roles(SystemRoles.ADMIN) on endpoints, service-level check for executive-only role assignments
• Existing to extend/replace: AdminStatsController at APIs/backend-api/src/app/admin/admin-stats.controller.ts

2.3 Implement components (13 total)

• What: All 13 components from the spec. Base on gmodules1 versions, update for:
  • inject() instead of constructor DI
  • autoFlashState instead of NGXS selectors
  • Real API service calls instead of mock
  • Corrected role hierarchy (executive at top)
  • Separate .ts, .html, .scss files (no inline templates)
• Why: The UI layer
• Effort: 8-12 hours (spread across components)
• Dependencies: Models (1.2), State (1.3), API Services (2.1)
• Order: user-avatar → user-card → user-filters → user-delete-confirm → multi-role-lookup → user-role-manager → user-form → user-list → user-detail → role-form → role-list → role-detail → user-list-widget

Tier 3 — Large or transformative work

3.1 Implement routes with guards and permissions

• What: user-management.routes.ts and role-management.routes.ts with authGuard, contextGuard, permissionGuard, roleGuard composition
• Why: Completes the module routing
• Effort: 2-3 hours
• Dependencies: Components (2.3)
• Note: permissionGuard may need to be created if it doesn't exist in the module framework's shared guards. Verify before implementing.

3.2 Module manifest and integration

• What: user-management.module.ts with @ModuleDecorator, lifecycle methods, navigation menu, public actions, embeddable widgets
• Why: Makes the module discoverable and integrable by the platform
• Effort: 2-3 hours
• Dependencies: All above

3.3 Follow-up: Dynamic CRUD generation for platforms

• What: Discuss and design how modules discover and connect to backend APIs in generated platforms. This affects not just user-management but ALL modules.
• Why: The user explicitly requested this conversation after the user-management module is done
• Effort: Design discussion (no implementation yet)
• Dependencies: User-management module working as reference implementation

6. The One Highest-Leverage Next Step

Write the implementation plan using the writing-plans skill, then start with models + autoFlashState (Tier 1.1 → 1.2 → 1.3).

Why: The models are the foundation everything else depends on. Getting the types right (with the corrected L0-L4 hierarchy, both SystemRoles and RegistrationUserType, proper request/response contracts) prevents cascading type errors across all other layers. The autoFlashState migration is small but critical — it removes the NGXS dependency that blocks portability.

The backend endpoints (Tier 2.2) can be built in parallel by a separate agent if available, since they're independent of the frontend work.

7. Files / Systems to Inspect

Frontend Module (Primary Target)

modules/core-modules/user-management/src/lib/
├── models/                    # UPDATE: Add executive, align with auth.types.ts
├── services/                  # REPLACE: Wire to real backend, not mock
├── state/                     # REPLACE: NGXS → autoFlashState
├── components/                # UPDATE: 8 → 13, modernize patterns
├── data/repositories/         # UPDATE: Wire to real API services
├── actions/                   # KEEP: Public actions for cross-module use
├── events/                    # KEEP: Domain events
├── mocks/                     # KEEP: For dev/test, but not default
├── user-management.module.ts  # UPDATE: Module manifest
└── user-management.routes.ts  # UPDATE: Add role routes, fix guards

gmodules1 Reference (Source for Rebuild)

/Users/fguijarro/developer/repos-gspace/gmodules1/libs/modules/user-management/src/lib/

This has the 13-component structure, modern patterns, workflow state machine, and role management that gspace1's module lacks.

Backend API (Endpoints to Add)

APIs/backend-api/src/app/admin/admin-stats.controller.ts  # Existing, to extend
APIs/backend-api/src/app/admin/admin-stats.service.ts     # Existing service
APIs/backend-api/src/app/users/users.controller.ts        # DO NOT modify (has /me/* routes)
APIs/backend-api/src/app/users/users.service.ts           # Existing, may reuse methods
libs/libs-api/backend-core/src/lib/schemas/user.schema.ts # User schema, may need status field
libs/libs-api/backend-core/src/lib/schemas/               # Add role.schema.ts here

Auth & Types (Already Fixed in S209)

libs/libs-ui/auth-ui/src/lib/models/auth.types.ts         # UserRole now includes 'executive'
libs/libs-api/auth-core/src/lib/auth-core.constants.ts     # SystemRoles, ADMIN_ROLES
libs/libs-api/auth-core/src/lib/guards/roles.guard.ts      # Hierarchy-aware guard

Storage System (autoFlashState Reference)

libs/libs-foundational/storage-system/src/flash/helpers/auto-flash-state.ts  # Main API
libs/libs-foundational/storage-system/src/flash/index.ts                     # Exports
docs/english/GoGrab-Space/theme-system/flash-persistence-integration.md      # Usage examples
docs/english/GoGrab-Space/docs.libs/docs.libs-foundational/storage-system/   # Full docs

Key import: import { autoFlashState } from '@storage-system' Returns: AutoFlashSignal<T> — a WritableSignal<T> with .hydrated signal

Types to Carefully Review

• UserRole in auth.types.ts — must include executive
• RegistrationUserType in auth.types.ts — L2+ types only (space_builder, space_admin, space_user, platform_user)
• SystemRoles in auth-core.constants.ts — 7 roles including EXECUTIVE
• ROLE_HIERARCHY in roles.guard.ts — levels 10-100
• VittoConfigRole in vitto-config.service.ts — maps to developer/platform_builder/end_user tiers

8. Validation Checklist

Before Implementation

• Verify @storage-system path alias resolves in tsconfig.base.json (line ~1084)
• Verify gmodules1 user-management module structure matches exploration report from S209
• Verify BaseCrudApiService exists in gmodules1 shared libs (if not, build standalone service)
• Verify permissionGuard exists in the module framework (if not, create or use alternative)
• Check if User schema in backend-api already has a status field

After Implementation

• yarn build modules-core-modules-user-management compiles without errors
• All 13 components render correctly with mock data (dev mode)
• autoFlashState persists UI preferences across page refresh
• Cross-tab sync works for filter/view mode changes
• Backend CRUD endpoints work via Postman/curl
• Role hierarchy enforcement: executive can manage all, admin can't assign executive role, manager can't modify admins
• Workflow state machine: pending → active → suspended → inactive transitions work with confirmation dialogs
• Module routes are guarded by permission and role guards
• Bulk operations (activate, deactivate, delete, changeRole) work for multi-selected users

Edge Cases

• User tries to assign a role HIGHER than their own → must be rejected (API + UI)
• Last admin tries to delete themselves → must be prevented
• Bulk delete includes the requesting user → must be excluded
• User with editor role accesses /users/admin/manage → must be denied
• autoFlashState .hydrated signal: operations that depend on persisted state must wait for hydration
• Generated platform with no NGXS → module must still work (verify no NGXS imports remain)

9. MCP and Codebase Guidance

The next agent MUST use mcp-gograb-ai tools for context and decision logging:

Session Setup

preflight({ task: "User-management module implementation", sessionNumber: 210 })
session({ action: "set", sessionNumber: 210, subSessionNumber: 2 })

Before Major Decisions

find_similar({ query: "user management module CRUD" })
intelligence({ action: "recall", situation: "module modernization pattern" })
convention({ action: "get", category: "angular" })

After Implementation Steps

log_decision({ type: "implementation", question: "...", chosen: "...", reasoning: "...", confidence: 0.9, files: [...] })
outcome({ action: "report", decisionId: "...", wasSuccessful: true/false })

If Encountering Issues

intelligence({ action: "simulate", simulateAction: "...", context: "...", alternatives: [...] })
intelligence({ action: "calibrate", rawConfidence: 0.X, domain: "angular" })

Key Conventions Already Established

• Convention conv_1773339124388_yjmtt: Executive endpoints must use @Roles(SystemRoles.EXECUTIVE)
• Convention conv_1773339127593_otg1q: Tier hierarchy L0=executive, never L0=developer

10. COPY/PASTE PROMPT FOR SESSION 210

You are continuing Session 210 (sub-session 2+) on branch `session-210`.

## Mission
Implement the user-management module modernization based on the approved spec at:
`docs/superpowers/specs/2026-03-12-user-management-module-modernization-design.md`

## Current State
- Branch: `session-210`
- Spec: Complete and reviewed (sub-session 210.1)
- Governance fixes: Complete (8 files updated in S209 — tier hierarchy, role guards, executive role)
- Implementation: NOT STARTED

## What Needs to Be Built (in order)

1. **Write implementation plan** — Use the `writing-plans` skill to convert the spec into a step-by-step build plan
2. **Models & types** — Update `modules/core-modules/user-management/src/lib/models/` with corrected L0-L4 hierarchy, both SystemRoles and RegistrationUserType, proper request/response contracts
3. **autoFlashState integration** — Replace NGXS state with `autoFlashState` from `@storage-system` for UI state (filters, pagination, viewMode, bulkSelection). Import: `import { autoFlashState } from '@storage-system'`
4. **API Service + Repository layers** — `UserApiService`, `RoleApiService` with configurable base URL. `UserRepository`, `RoleRepository` wrapping the API services.
5. **Backend-api enhancements** — New `AdminUsersController` at `/api/admin/users` with full CRUD + status + roles + bulk. New `Role` schema. Located at `APIs/backend-api/src/app/admin/`.
6. **Components (13 total)** — Base on gmodules1 versions at `/Users/fguijarro/developer/repos-gspace/gmodules1/libs/modules/user-management/src/lib/`. Modernize: standalone, OnPush, inject(), signals, autoFlashState, separate .ts/.html/.scss files.
7. **Routes with guards** — User routes + role routes with authGuard, permissionGuard, roleGuard composition.
8. **Module manifest** — `@ModuleDecorator` with lifecycle, navigation, public actions, embeddables.

## Critical Rules
- NEVER use NGXS — use `autoFlashState` from `@storage-system` for persistent UI state
- All components: standalone, OnPush, inject(), signals, separate files
- All async: RxJS Observables only — no Promises, no setTimeout
- API base URL must be injectable (not hardcoded) — for portability to generated platforms
- Role hierarchy: executive(90) > developer(80) > admin(60) > manager(40) > editor(20) > viewer(10)
- Two classification systems: `role` (UserRole — access control) vs `userType` (RegistrationUserType — hierarchy category)
- Backend endpoints at `/api/admin/users` (NOT `/api/users` — that path has existing `/me/*` routes)
- Use `@Roles(SystemRoles.ADMIN)` on all admin endpoints, with service-level check for executive-only role assignments
- Follow `docs/english/Prompts/global-engineering-standard.md` for code quality

## Key Files to Read First
1. `docs/superpowers/specs/2026-03-12-user-management-module-modernization-design.md` — THE SPEC
2. `modules/core-modules/user-management/src/` — Current gspace1 module (to be replaced)
3. `/Users/fguijarro/developer/repos-gspace/gmodules1/libs/modules/user-management/src/` — gmodules1 reference (source for rebuild)
4. `libs/libs-ui/auth-ui/src/lib/models/auth.types.ts` — UserRole, RegistrationUserType
5. `libs/libs-api/auth-core/src/lib/auth-core.constants.ts` — SystemRoles
6. `libs/libs-foundational/storage-system/src/flash/helpers/auto-flash-state.ts` — autoFlashState API
7. `docs/english/GoGrab-Space/theme-system/flash-persistence-integration.md` — autoFlashState usage examples

## MCP Setup
Run these at session start:
- preflight({ task: "User-management module implementation", sessionNumber: 210 })
- session({ action: "set", sessionNumber: 210, subSessionNumber: 2 })
- convention({ action: "get", category: "angular" })

## Follow-up Discussion (After Module is Complete)
The user wants to discuss dynamic CRUD generation strategy for platforms — how modules discover and connect to their backend APIs in generated platforms. Flag this for discussion once the user-management module is working.

## Git Protocol
- Commits: `[S210.{sub}] type: description`
- Staging: `git add <specific-files>` — NEVER `git add .`
- Sub-session: increment from last known (start at 210.2)